클로드 코드 완벽 가이드 — 20장 테스트 작성하기 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

20장에서 다루는 내용

• 테스트의 필요성 — 왜 자동화된 테스트가 수동 테스트보다 효율적인지
• 테스트 코드 계획하기 — 클로드 코드와 대화하며 테스트 구조/계획 수립
• 유닛 테스트 작성 — 서브에이전트를 활용한 병렬 테스트 코드 작성
• E2E 테스트 계획 및 작성 — Playwright와 MCP를 활용한 통합 테스트

전체 흐름도

[테스트 코드 계획하기]          [유닛 테스트 작성하기]          [E2E 테스트 작성하기]
    |                              |                              |
    v                              v                              v
+------------------------+  +---------------------------+  +---------------------------+
| 01 테스트 구조 구상      |  | 01 서브에이전트 분담 계획  |  | 01 Playwright 구조 구상   |
| - __tests__/ 폴더 설계   |  | - Agent 1: 핵심 로직       |  | - tests/ 폴더 설계         |
| - lib/ components/      |  | - Agent 2: React 컴포넌트  |  | - auth/ cities/ core/     |
|   hooks/ __mocks__/     |  | - Agent 3: Hooks & Auth   |  |   fixtures/ page-objects/ |
|                          |  | - Agent 4: 인프라          |  |   utils/                  |
| 02 테스트 계획 작성       |  |                            |  |                           |
| - 우선순위별 분류         |  | 02 병렬 실행              |  | 02 Playwright 세팅        |
| - HIGH/MEDIUM/LOW       |  | - 3~4개 에이전트 동시 실행 |  | - playwright.config.ts    |
| - 기능별 시나리오 정리    |  | - 65~70% 시간 단축        |  | - package.json 스크립트   |
|                          |  |                            |  |                           |
|                          |  | 03 테스트 실행/검증       |  | 03 CLAUDE.md에 구조 등록  |
|                          |  | - Jest 단위 테스트 실행    |  | 04 Playwright MCP 등록    |
|                          |  | - 95개 테스트 통과         |  | 05 커스텀 커맨드 생성     |
|                          |  |                            |  | 06 테스트 실행/리포트     |
+------------------------+  +---------------------------+  +---------------------------+

선수 지식 체크리스트

• [ ] JavaScript/TypeScript 기본 문법
• [ ] React 컴포넌트 구조 (props, state, hooks)
• [ ] 클로드 코드 서브에이전트 개념 (병렬 처리)
• [ ] Node.js 패키지 관리 (npm, pnpm)
• [ ] 기본적인 테스트 용어 (유닛 테스트, E2E 테스트)

핵심 키워드

1. 테스트 코드를 왜 작성해야 하는가?

한 줄 요약

테스트 코드를 작성하지 않으면 프로젝트의 코드 품질을 보장할 수 없으며, 바이브 코딩 환경에서는 오히려 더 중요하다.

쉬운 설명 (비유)

비유: 건강 검진 vs 아플 때만 병원 가기

❌ 수동 테스트 = "만들어서 돌려보면 되지 뭐"
  → 시간이 많이 들고, 실수할 수 있음
  → 기능이 많아지면 일일이 확인하기 불가능

✅ 자동화된 테스트 = "정기 건강 검진"
  → 반복해서 빠르게 검증 가능
  → 새 코드가 기존 코드에 미치는 영향을 즉시 확인
  → 버그가 있는 코드를 자동으로 재확인

클로드 코드에서 테스트가 특히 중요한 이유

클로드 코드는 현재 콘텍스트 윈도우에서 변경한 내용이
기존 코드와 통합될 때 어떤 영향이 있을지 확인한다.
그리고 버그가 있을 수 있는 코드를 재확인한다.

→ 테스트 코드가 있으면 클로드 코드가 "자동으로" 품질을 검증한다!

실무 예제

# 수동 테스트 vs 자동 테스트 비교

수동 테스트 (매번 반복해야 함):
1. 브라우저 열기
2. 로그인하기
3. 좋아요 버튼 클릭
4. 새로고침 후 좋아요 유지 확인
5. 싫어요로 변경
6. 다시 새로고침...
→ 기능 하나 바꿀 때마다 이걸 반복? 😱

자동 테스트 (한 번 작성하면 끝):
$ npx jest
✅ 35개 테스트 모두 통과 (0.5초)
→ 코드 변경할 때마다 자동으로 검증!

핵심 체크포인트

• [ ] 수동 테스트의 한계(시간, 실수 가능성)를 이해했는가?
• [ ] 자동화된 테스트의 장점(반복성, 속도, 일관성)을 설명할 수 있는가?
• [ ] 클로드 코드가 테스트 코드를 활용하는 방식을 이해했는가?

2. 테스트 코드 계획하기

한 줄 요약

클로드 코드에게 처음부터 테스트 코드를 작성시키지 말고, 먼저 테스트 구조와 계획을 대화로 수립한 뒤 단계적으로 진행한다.

쉬운 설명 (비유)

비유: 요리하기 전에 레시피 먼저 짜기

❌ 바로 코딩: "테스트 코드 작성해줘"
  → 구조가 없으니 뒤죽박죽

✅ 계획 먼저: "테스트 구조를 구상해줘. 아직 작성하지는 말아줘."
  → 폴더 구조 → 테스트 목록 → 우선순위 → 그 다음에 코드 작성

단계 01: 테스트 구조 구상

클로드 코드에게 프로젝트 구조를 파악하고 유닛 테스트 코드를 작성할 구조를 구상해달라고 요청한다. 핵심: "아직 테스트 코드를 작성하지는 말아줘"

프롬프트 예시:
"현재 프로젝트 구조를 파악하고 유닛 테스트 코드를 작성할 구조를 구상해줘.
아직 테스트 코드를 작성하지는 말아줘."

클로드 코드가 제안하는 테스트 구조 예시:

__tests__/
├── lib/
│   ├── preferences.test.ts     # 핵심 비즈니스 로직
│   ├── cities.test.ts           # 필터링 로직
│   └── utils.test.ts            # 유틸리티 함수
├── components/
│   ├── cities/
│   │   └── CityCard.test.tsx    # 도시 카드 상호작용
│   └── home/
│       ├── HeroSection.test.tsx # 필터 UI
│       └── TopCities.test.tsx   # 도시 목록 UI
├── hooks/
│   └── useLocalStorageMigration.test.ts
└── __mocks__/
    ├── supabase.ts              # Supabase 모킹
    ├── next-router.ts           # Next.js 라우터 Mock
    └── localStorage.ts          # localStorage 모킹

단계 02: 테스트 계획 작성

테스트 폴더 구조가 마음에 들면, 어떤 파일의 어떤 기능을 어떤 시나리오로 테스트할지 정리를 요청한다.

프롬프트 예시:
"작성해야 할 유닛 테스트를 전부 정리해줘. 아직 테스트 코드를 작성하지는 말아줘."

클로드 코드가 우선순위별로 분류하여 테스트 목록을 정리한다:

테스트 우선순위별 분류

HIGH PRIORITY - 핵심 비즈니스 로직
1. src/lib/preferences.ts - 사용자 선호도 관리
   - toggleCityPreference() 함수
     - 좋아요 추가 (null → like)
     - 좋아요 취소 (like → null)
     - 좋아요에서 싫어요로 변경 (like → dislike)
     - 싫어요 추가 (null → dislike)
     - 싫어요 취소 (dislike → null)
     - 싫어요에서 좋아요로 변경 (dislike → like)
     - Supabase 에러 시 localStorage fallback
     - 네트워크 에러 시 localStorage fallback
   ...생략...

실무 예제

# 실제 대화 흐름 (4단계 전략)

1단계: "프로젝트 구조를 파악하고 테스트 코드 구조를 구상해줘. 아직 작성하지 마."
   → 폴더 구조 확인

2단계: "작성해야 할 유닛 테스트를 전부 정리해줘. 아직 코드 작성하지 마."
   → 테스트 목록 및 우선순위 확인

3단계: "지금까지의 계획을 기반으로 Subagent를 사용해서 Parallel하게
        테스트 코드 작성 과정을 병행으로 진행할 수 있는지 계획을 보여줘."
   → 서브에이전트 분담 계획 확인

4단계: "계획을 기반으로 테스트 코드 작업을 진행해줘."
   → 실제 테스트 코드 작성

핵심 체크포인트

• [ ] 테스트 구조 구상 → 테스트 계획 → 코드 작성 순서를 이해했는가?
• [ ] "아직 작성하지 마"라는 제약 조건을 프롬프트에 넣는 이유를 설명할 수 있는가?
• [ ] 우선순위별(HIGH/MEDIUM/LOW) 테스트 분류를 할 수 있는가?

3. 유닛 테스트 작성하기 (서브에이전트 병렬 활용)

한 줄 요약

서브에이전트를 병렬로 실행하면 독립적인 유닛 테스트를 동시에 작성할 수 있어 65~70%의 시간을 절약할 수 있다.

쉬운 설명 (비유)

비유: 시험 채점

❌ 순차 개발 = 선생님 1명이 모든 과목 채점
  → 9~13시간 소요

✅ 병렬 개발 = 4명의 선생님이 각자 담당 과목 채점
  → 3~4시간 소요 (65~70% 시간 절약)

서브에이전트 역할 분담 계획

Agent 1: Core Logic Specialist (핵심 비즈니스 로직)
├── __tests__/lib/preferences.test.ts   # 복잡도: HIGH
├── __tests__/lib/cities.test.ts        # 복잡도: HIGH
└── __tests__/lib/fallback-data.test.ts # 복잡도: MEDIUM
→ 테스트 케이스: ~45개 | 예상 소요: 4~5시간

Agent 2: React Component Specialist (UI 컴포넌트)
├── __tests__/components/cities/CityCard.test.tsx    # 복잡도: HIGH
├── __tests__/components/home/HeroSection.test.tsx   # 복잡도: MEDIUM
└── __tests__/components/home/TopCities.test.tsx     # 복잡도: MEDIUM
→ 테스트 케이스: ~28개 | 예상 소요: 3~4시간

Agent 3: Hooks & Auth Specialist (React Hooks, 인증)
├── __tests__/hooks/useLocalStorageMigration.test.tsx # 복잡도: MEDIUM
├── __tests__/components/auth/UserMenu.test.tsx       # 복잡도: MEDIUM
└── __tests__/lib/utils.test.ts                       # 복잡도: LOW
→ 테스트 케이스: ~18개 | 예상 소요: 2~3시간

Agent 4: Infrastructure Specialist (테스트 환경/Mock)
├── __tests__/__mocks__/supabase.ts      # Mock 시스템
├── __tests__/__mocks__/next-router.ts   # 라우터 Mock
├── __tests__/__mocks__/localStorage.ts  # localStorage Mock
├── __tests__/__mocks__/city-data.ts     # 테스트 데이터
└── jest.config.js + jest.setup.js       # 테스트 환경 설정
→ 예상 소요: 1~2시간

병렬 개발 성과

┌─────────────────────────────────────────────┐
│ 3개 Agent 동시 실행 결과                      │
│                                               │
│ Agent 1 - Core Logic: 103개 테스트 (71% 통과) │
│ Agent 2 - React: CityCard 27/27 (100% 성공)  │
│ Agent 3 - Hooks & Auth: 62개 테스트 (100%)   │
│                                               │
│ 총 17개 테스트 파일, 238개 테스트 케이스      │
│ 핵심 기능 82% 성공률 검증                     │
│                                               │
│ 순차 개발: 9~13시간                           │
│ 병렬 개발: 3~4시간                            │
│ 시간 절약: 5~9시간 (65~70% 단축)              │
└─────────────────────────────────────────────┘

Jest 테스트 실행 결과 예시

테스트 실행 결과 요약
Jest 단위 테스트 ✅ 성공

95개 테스트 모두 통과 - 4개 테스트 스위트 실행 완료

테스트 범위:
1. 유틸리티 함수 (cn 함수) - 31개 테스트
   - 클래스명 병합, 조건부 클래스, Tailwind 중복 제거 등
2. 폴백 데이터 관리 - 26개 테스트
   - 레거시 데이터 변환, localStorage 통합, 성능 테스트
3. 사용자 선호도 시스템 - 35개 테스트
   - 좋아요/싫어요 토글, DB/localStorage 폴백, 마이그레이션
4. 도시 필터링 로직 - 31개 테스트
   - 지역/예산/환경/계절 필터링, 복합 필터링

실무 예제

// Jest 유닛 테스트 예시 - 사용자 선호도 토글
describe('toggleCityPreference', () => {
  test('좋아요 추가 (null → like)', () => {
    const result = toggleCityPreference(null, 'like');
    expect(result).toBe('like');
  });

  test('좋아요 취소 (like → null)', () => {
    const result = toggleCityPreference('like', 'like');
    expect(result).toBeNull();
  });

  test('좋아요에서 싫어요로 변경 (like → dislike)', () => {
    const result = toggleCityPreference('like', 'dislike');
    expect(result).toBe('dislike');
  });
});

핵심 체크포인트

• [ ] 유닛 테스트가 "작은 단위별, 독립적으로" 작성됨을 이해했는가?
• [ ] 서브에이전트 병렬 활용의 장점(시간 절약)과 주의점(충돌 가능성)을 이해했는가?
• [ ] Mock(모킹)이 왜 필요한지 설명할 수 있는가?
• [ ] 병렬 실행 시 Agent 4(인프라)를 먼저 완료한 후 나머지를 병렬로 진행하는 이유를 아는가?

4. E2E 테스트 계획하기

한 줄 요약

유닛 테스트가 최소한의 품질 보장이라면, E2E 테스트는 사용자가 주도하여 실제 브라우저에서 사용자 시나리오를 검증하는 테스트이다.

쉬운 설명 (비유)

비유: 자동차 검사

유닛 테스트 = 엔진, 브레이크, 타이어를 각각 따로 검사
  → "부품별로는 괜찮은데, 조립하면 문제 없나?"

통합 테스트 = 엔진+브레이크+타이어를 함께 검사
  → "부품 간 연결이 잘 되나?"

E2E 테스트 = 실제로 도로에서 운전해보기
  → "사용자가 시동 걸고 → 출발하고 → 브레이크 밟고 → 주차하는 전체 과정"

유닛 테스트 vs E2E 테스트

Playwright E2E 테스트 구조

tests/                          # E2E 테스트 루트 디렉토리
├── auth/                       # 인증 관련 테스트
│   ├── login.spec.ts
│   ├── register.spec.ts
│   └── logout.spec.ts
├── cities/                     # 도시 관련 테스트
│   ├── city-filtering.spec.ts
│   ├── city-preferences.spec.ts
│   └── city-navigation.spec.ts
├── core/                       # 핵심 기능 테스트
│   ├── homepage.spec.ts
│   ├── navigation.spec.ts
│   └── responsive.spec.ts
├── fixtures/                   # 테스트 데이터 및 설정
│   ├── test-data.ts
│   ├── mock-cities.ts
│   └── user-accounts.ts
├── page-objects/               # Page Object Model 클래스
│   ├── base-page.ts
│   ├── login-page.ts
│   ├── home-page.ts
│   └── city-card.ts
└── utils/                      # 테스트 유틸리티
    ├── auth-helpers.ts
    ├── database-helpers.ts
    └── screenshot-helpers.ts
playwright.config.ts            # Playwright 설정

핵심 체크포인트

• [ ] 유닛 테스트 → 통합 테스트 → E2E 테스트의 계층 구조를 이해했는가?
• [ ] E2E 테스트를 "사용자가 주도"해야 하는 이유를 설명할 수 있는가?
• [ ] Page Object Model 패턴의 목적을 이해했는가?
• [ ] fixtures/와 page-objects/ 폴더의 역할을 구분할 수 있는가?

5. E2E 테스트 작성하기 (Playwright + MCP)

한 줄 요약

Playwright MCP를 등록하고 커스텀 커맨드를 만들면, 자연어로 테스트할 요소를 입력해도 Playwright API로 변환하여 E2E 테스트 코드를 자동 생성할 수 있다.

쉬운 설명 (비유)

비유: 레스토랑 주문

❌ 직접 요리: Playwright API를 일일이 손으로 작성
  → page.goto(), page.getByRole(), expect().toBeVisible() ...

✅ 주문만 하기: 자연어로 "이거 테스트해줘"
  → 클로드 코드 + Playwright MCP가 자동으로 테스트 코드 작성
  → 실제 브라우저에서 실행까지 해줌

단계별 E2E 테스트 세팅

단계 01: Playwright 구조 구상 및 세팅

프롬프트:
"E2E 테스트를 Playwright를 사용해서 구현할 건데
 폴더 구조를 어떻게 하면 좋을지 구상해줘. 아직 테스트를 작성하지는 말아줘."
→ 구조 확인 후:
"계획대로 Playwright 테스트 구조를 만들기 위해 Playwright 세팅을 해주고
 테스트 폴더 구조를 구현해줘. 아직 테스트는 작성하지 말아줘."

완료된 작업: - @playwright/test 패키지 설치 - playwright.config.ts 설정 파일 생성 - tests/ 폴더 구조 생성 (auth/, cities/, core/, fixtures/, page-objects/, utils/) - package.json에 E2E 테스트 스크립트 5개 추가 - fixtures, utils, page-objects 기본 파일 생성

단계 02: CLAUDE.md에 E2E 테스트 구조 등록

프롬프트:
"CLAUDE.md 파일에 E2E 테스트 구조에 대한 설명을 작성해줘."
→ 이후 클로드 코드가 테스트 코드를 생성할 때마다 참조할 수 있게 됨

단계 03: Playwright MCP 등록

# 터미널에서 실행
claude mcp add playwright -s project npx @playwright/mcp@latest

등록 결과 (.mcp.json):

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {}
    }
  }
}

단계 04: 커스텀 커맨드로 E2E 테스트 자동 생성

# 파일: .claude/commands/create-e2e-test.md

# E2E 테스트 생성기
너는 지금부터 Playwright로 E2E 테스트를 생성하는 QA 전문가야.
## 테스트 방식
- $ARGUMENT로 입력한 테스트 요소들을 잘 이해해줘.
- Playwright MCP를 사용해서 테스트를 진행해줘.
- 테스트가 전부 끝나면 E2E 테스트를 작성해줘.
- 작성한 테스트들을 전부 실행해주고 실패하는 테스트가 있다면 성공할 때까지 개선해줘.

단계 05: 커스텀 커맨드 실행

/create-e2e-test
- http://localhost:3000으로 이동해줘
- 홈페이지에 로고가 존재하는 걸 확인해줘
- 홈페이지에 도시 카드들이 존재하는 걸 확인해줘
- 홈페이지에 처음 접속하면 필터가 적용 안 돼 있는걸 확인해줘
- 홈페이지의 필터가 적용 안 돼 있으면 데이터베이스에 저장된 도시들이
  전부 도시 카드로 나열 돼 있는 걸 확인해줘.

실무 예제: Playwright E2E 테스트 코드

test.describe('K-NOMAD 홈페이지 기본 기능 테스트', () => {
  test.beforeEach(async ({ page }) => {
    // 각 테스트 전에 홈페이지로 이동
    await page.goto('http://localhost:3000');
  });

  test('홈페이지에 로고가 존재하는지 확인', async ({ page }) => {
    // 헤더의 K-NOMAD HUB 로고 확인
    const headerLogo = page.getByRole('link', { name: 'K-NOMAD HUB' });
    await expect(headerLogo).toBeVisible();

    // 로고가 클릭 가능한지 확인
    await expect(headerLogo).toHaveAttribute('href', '/');
  });
  // ...생략...
});

테스트 실행 및 결과 확인

# 모든 테스트 실행 (모든 브라우저)
npx playwright test

# 마지막 테스트 결과 리포트 열기
npx playwright show-report

Playwright는 실제 브라우저(Chromium, Firefox)를 사용하여 테스트하므로, 실패 시 스크린샷과 동영상까지 제공한다. 유닛 테스트보다 개발자가 더 직관적으로 테스트 결과를 확인할 수 있다.

핵심 체크포인트

• [ ] Playwright MCP를 등록하는 명령어(claude mcp add)를 알고 있는가?
• [ ] 커스텀 커맨드(.claude/commands/)로 E2E 테스트 생성을 자동화하는 방법을 이해했는가?
• [ ] npx playwright test와 npx playwright show-report 명령어의 차이를 아는가?
• [ ] Playwright가 실패 시 스크린샷/동영상을 제공하는 장점을 설명할 수 있는가?

연습문제

문제 1 (기본)

유닛 테스트, 통합 테스트, E2E 테스트의 차이점을 설명하고, 각각 어떤 상황에서 사용하는 것이 적합한지 예시를 들어 설명하시오.

문제 2 (중급)

클로드 코드의 서브에이전트를 활용하여 테스트 코드를 병렬로 작성할 때, Agent 4(Infrastructure Specialist)를 먼저 완료한 후 나머지를 병렬로 진행해야 하는 이유를 설명하시오.

문제 3 (심화)

Playwright MCP를 활용한 E2E 테스트 자동화 워크플로우를 처음부터 끝까지 설계하시오. 필요한 파일, 설정, 커맨드를 모두 포함하시오.

부록 A — 용어 사전

부록 B — 비교표

테스트 유형 비교

서브에이전트 역할별 비교

순차 개발 vs 병렬 개발

부록 C — 참고 자료